---
title: PostGraphile V5 release candidate! 🎉
description:
  The code is done, the docs and types need some love. Help us prepare for the
  release of PostGraphile V5!
slug: 2025-10-28-v5-release-candidate
authors: [benjie, jem]
tags: [releases, v5]
hide_table_of_contents: false
toc_max_heading_level: 2
---

import styles from "@site/src/css/common.module.css";

<div className={styles.intro}>

After over 100 releases, PostGraphile V5
has finally reached **release candidate** status! 🎉 Assuming no issues are found,
this software, these APIs, are what will make up the final PostGraphile v5.0
release! The runtime is ready, many of you are already using it in production,
but the types and docs are a little behind. Help us get ready for release: try
it out, tell us where the gaps are, and maybe help fill them!

</div>

## Five years in the making, PostGraphile V5 raises the bar again

After a couple false starts, in February 2020 we kicked off the journey that
would ultimately become PostGraphile V5 and the [Gra*fast* planning and execution
engine](https://grafast.org). Since January 2023 we have shipped 38 pre-alpha,
20 alpha, and 49 beta releases. Every stage refined the ergonomics, uncovered
tricky edge cases, and ultimately solved the four Gra*fast* epics that blocked a
stable release:

- ✅ Everything is batched, but “unary” values (variables, context, etc) are now treated as a special case.
- ✅ Early termination of field execution with a `null` now has first-class
  support.
- ✅ Plan-time “peeking” at runtime values is now forbidden, improving plan
  re-use.
- ✅ The exponential polymorphic branching hazard is now eradicated by
  converging before branching again.

The result is a platform that is faster, more expressive, more configurable, and
easier to extend than anything we have shipped before.

<!-- truncate-->

## Why this is still a release candidate

We do not anticipate breaking changes to the runtime behaviour. Numerous
teams have already trusted beta builds in production for over a year and the
feedback has been excellent. The remaining work is polish: verifying the docs,
catching stray rough edges, and ensuring that migration guidance reflects the
software as it exists today.

You can expect the occasional breaking change in TypeScript typings as we close
gaps and fix inaccuracies. The runtime APIs will remain compatible, but you may
need to adjust type annotations while we tighten things up. Likewise, some TSDoc
comments are behind reality; we will update them alongside the docs.

If you bump into rough edges while trying V5, please raise an issue in the
[Crystal repo](https://github.com/graphile/crystal) so we can address it before
the final release.

## Help us finish the documentation

The code moved faster than the words that describe it. Parts of the docs are
out of date, others are missing, and a few contradict the behaviour you see in
practice. We need review, issue reports, and small patches. Your first-hand notes
about what is unclear are invaluable.

- Walk through the guides and flag inaccuracies.
- Suggest examples that clarify tricky concepts.
- Contribute short how-tos drawn from your own migration.
- Help us verify CLI reference pages against the current defaults.

Please [open issues or pull requests](https://github.com/graphile/crystal) and
talk to us on [Discord](https://discord.gg/graphile). We are prioritizing
documentation and type improvements above new features during the RC period.

## Try the release candidate today

Install the release candidate from npm; you should use the `@rc` tag with all of
our modules to get the V5 version:

```bash
yarn add postgraphile@rc
```

You can also try the bundled CLI without installing (no tag needed here since
it’s new!):

```bash
npx pgl -P pgl/amber -e -c postgres:///my_db -s public
```

Replace the connection string and schema with your own values.

## Migrating from V4?

If you are upgrading from V4, follow the [migration
guide](/postgraphile/5/migrating-from-v4) and let us know where it can be
improved.

We’re particularly interested to hear how you get on, and what tools help with
your migration. If you’re using AI code assistants, what instructions did you
give? Can we clarify anything in the migration guide so they have greater
success?

## Thank you sponsors!

PostGraphile is crowd-funded open-source software. The sponsors listed on
[graphile.org](https://graphile.org/sponsor) have funded the years of work that
brought us to this moment. If PostGraphile helps your team ship faster or run
leaner infrastructure, please ask your company to become a sponsor so that we
can keep investing in the project.

<figure>

![Thank you](../static/img/news/thank-you.svg)

</figure>
